occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/errors/parsing_error.rb

@@ -0,0 +1,11 @@
+module Occi
+  module Core
+    module Errors
+      # Custom error class indicating parsing failures on
+      # various renderings.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      class ParsingError < StandardError; end
+    end
+  end
+end

data/lib/occi/core/errors/renderer_error.rb

@@ -0,0 +1,11 @@
+module Occi
+  module Core
+    module Errors
+      # Custom error class indicating internal renderer
+      # errors or non-compliance with the expected interface.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      class RendererError < StandardError; end
+    end
+  end
+end

data/lib/occi/core/errors/rendering_error.rb

@@ -0,0 +1,11 @@
+module Occi
+  module Core
+    module Errors
+      # Custom error class indicating rendering failures on
+      # various renderable instances.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      class RenderingError < StandardError; end
+    end
+  end
+end

data/lib/occi/core/errors/validation_error.rb

@@ -0,0 +1,11 @@
+module Occi
+  module Core
+    module Errors
+      # Custom error class indicating validation failures on
+      # various objects.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      class ValidationError < StandardError; end
+    end
+  end
+end

data/lib/occi/core/errors.rb

@@ -0,0 +1,9 @@
+module Occi
+  module Core
+    # Wrapper for all custom error classes. For details on intended
+    # use, see specific error classes within this module.
+    module Errors; end
+  end
+end
+
+Dir[File.join(File.dirname(__FILE__), 'errors', '*.rb')].each { |file| require file.gsub('.rb', '') }

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

@@ -0,0 +1,27 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces argument validation capabilities to every receiver
+      # class. Should be used via the `include` or `extend` keywords.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module ArgumentValidator
+        # :nodoc:
+        def default_args!(args)
+          args.merge!(defaults) { |_, oldval, _| oldval }
+          sufficient_args!(args)
+        end
+
+        # :nodoc:
+        def sufficient_args!(args); end
+
+        # :nodoc:
+        def defaults
+          {}
+        end
+
+        private :defaults, :sufficient_args!, :default_args!
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces attributes accessor as a shortcut to
+      # getting to the `attributes` values inside the
+      # receiver.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module AttributesAccessor
+        # :nodoc:
+        def [](key)
+          attributes[key]
+        end
+
+        # :nodoc:
+        def []=(key, val)
+          attributes[key] = val
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces additional error handling functions to the receiver
+      # class and its instnaces.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module ErrorHandler
+        # Wraps potential exceptions raised in the given block in the specified
+        # exception class. Internal exception can be later exposed via `Exception#cause`.
+        #
+        # @param klass [Class] raise error of this class if necessary
+        def handle(klass)
+          raise 'You have to provide a block' unless block_given?
+          begin
+            yield # do whatever you need to do
+          rescue => ex
+            raise klass, ex.message
+          end
+        end
+
+        # :nodoc:
+        def self.included(klass)
+          klass.extend self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces hash dereferencing capabilities to `Hash`. This allowes
+      # hash instances containing `Occi::Core::Category` sub-types by
+      # identifier and `Occi::Core::AttributeDefinition` instances by name to be
+      # converted into proper objects.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module HashDereferencer
+        # Replaces all references to existing categories with actual instances from
+        # from the given model. Similar processing is done on attribute definitions
+        # referenced by attribute names.
+        #
+        # @param klass [Class] klass serialized in this hash
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_with!(klass, model, attribute_definitions)
+          unless model && attribute_definitions
+            raise 'Both `model` and `attribute_definitions` are ' \
+                  'required for dereferencing'
+          end
+
+          send(
+            "dereference_#{klass.to_s.demodulize.downcase}_with!",
+            model, attribute_definitions
+          )
+        end
+
+        # Replaces all references to existing categories with actual instances from
+        # from the given model. Similar processing is done on attribute definitions
+        # referenced by attribute names.
+        #
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_category_with!(model, attribute_definitions)
+          changed = 0
+
+          unless self[:actions].blank?
+            self[:actions].map! { |action| dereference_via_model(action, model) }
+            changed += self[:actions].count
+          end
+          self[:actions] = Set.new(self[:actions])
+          changed += dereference_attribute_definitions_with!(attribute_definitions)
+
+          changed
+        end
+
+        # Replaces all name-only references to existing attribute definitions with actual instances from
+        # from the given hash.
+        #
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_attribute_definitions_with!(attribute_definitions)
+          return 0 if self[:attributes].blank?
+
+          new_attributes = {}
+          self[:attributes].each do |attribute|
+            new_attributes[attribute] = dereference_via_hash(attribute, attribute_definitions)
+          end
+          self[:attributes] = new_attributes
+
+          self[:attributes].count
+        end
+
+        # Replaces all references to existing categories with actual instances from
+        # from the given model. Similar processing is done on attribute definitions
+        # referenced by attribute names.
+        #
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_kind_with!(model, attribute_definitions)
+          changed = 0
+
+          if self[:parent]
+            self[:parent] = dereference_via_model(self[:parent], model)
+            changed += 1
+          end
+          changed += dereference_category_with!(model, attribute_definitions)
+
+          changed
+        end
+
+        # Replaces all hashes with attribute definitions with valid instnaces of
+        # `Occi::Core::AttributeDefinition`.
+        #
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_action_with!(_model, _attribute_definitions)
+          return 0 if self[:attributes].blank?
+          # TODO: handle attributes referenced by name only
+          self[:attributes].each_pair do |key, val|
+            self[:attributes][key] = Occi::Core::AttributeDefinition.new(val.symbolize_keys)
+          end
+          self[:attributes].count
+        end
+
+        # Replaces all references to existing categories with actual instances from
+        # from the given model. Similar processing is done on attribute definitions
+        # referenced by attribute names.
+        #
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @param attribute_definitions [Hash] hash with known attribute definitions for dereferencing
+        # @return [Integer] number of changes made when dereferencing
+        def dereference_mixin_with!(model, attribute_definitions)
+          changed = 0
+
+          %i[depends applies].each do |symbol|
+            unless self[symbol].blank?
+              self[symbol].map! { |elm| dereference_via_model(elm, model) }
+              changed += self[symbol].count
+            end
+            self[symbol] = Set.new(self[symbol])
+          end
+          changed += dereference_category_with!(model, attribute_definitions)
+
+          changed
+        end
+
+        # Looks up the given category in the model. Raises error if no
+        # such category is found.
+        #
+        # @param identifier [String] category identifier
+        # @param model [Occi::Core::Model] model instance for dereferencing (category look-up)
+        # @return [Occi::Core::Category] instance located in the model
+        def dereference_via_model(identifier, model)
+          model.find_by_identifier!(identifier)
+        end
+
+        # Looks up the given attribute definition in the hash. Raises error if no
+        # such attribute definition is found.
+        #
+        # @param identifier [String] attribute identifier (name)
+        # @param hash [Hash] hash with known attribute definitions for dereferencing
+        # @return [Occi::Core::AttributeDefinition] definition located in the hash
+        def dereference_via_hash(identifier, hash)
+          raise "Attribute definition #{identifier.inspect} not found in the hash" unless hash[identifier]
+          hash[identifier]
+        end
+
+        private :dereference_via_hash, :dereference_via_model
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces validation capabilities to every receiver
+      # class. Should be used via the `extend` keyword.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module IdentifierValidator
+        # Characters prohibited in `schema` attribute
+        PROHIBITED_SCHEMA_CHARS = %w[% & ? ! \\].freeze
+
+        # Definition of characters allowed in `term` attribute
+        REGEXP_TERM = /^([[:alpha:]]|[[:digit:]])([[:alpha:]]|[[:digit:]]|-|_)*$/
+
+        # Validates given `term` against the restrictions imposed by the
+        # OCCI specification. See `REGEXP_TERM` in this class for details.
+        #
+        # @example
+        #   valid_term? 'a b' # => false
+        #   valid_term? 'ab'  # => true
+        #
+        # @param term [String] term candidate
+        # @return [TrueClass, FalseClass] result
+        def valid_term?(term)
+          begin
+            valid_term! term
+          rescue Occi::Core::Errors::CategoryValidationError => ex
+            logger.warn "#{self}: Term validation failed with #{ex.message}" if respond_to?(:logger)
+            return false
+          end
+
+          true
+        end
+
+        # Similar to `::valid_term?`, raises an `Occi::Core::Errors::CategoryValidationError`
+        # error in case of failure.
+        #
+        # @param term [String] term candidate
+        def valid_term!(term)
+          validation_result = REGEXP_TERM.match(term)
+
+          return if validation_result
+          raise Occi::Core::Errors::CategoryValidationError,
+                "Term #{term.inspect} does not match #{REGEXP_TERM.inspect}"
+        end
+
+        # Validates given `schema` against the restrictions imposed by the
+        # URI specification. See Ruby's `URI` class for details. On top of
+        # that, every schema must be terminated with '#'.
+        #
+        # @example
+        #   valid_schema? '%^#%^'                    # => false
+        #   valid_schema? 'http://example.org/test#' # => true
+        #
+        # @param schema [String] schema candidate
+        # @return [TrueClass, FalseClass] result
+        def valid_schema?(schema)
+          begin
+            valid_schema! schema
+          rescue URI::InvalidURIError, Occi::Core::Errors::CategoryValidationError => ex
+            logger.warn "#{self}: Schema validation failed with #{ex.message}" if respond_to?(:logger)
+            return false
+          end
+
+          true
+        end
+
+        # Similar to `::valid_schema?`, raises an `Occi::Core::Errors::CategoryValidationError`
+        # error in case of failure.
+        #
+        # @param schema [String] schema candidate
+        def valid_schema!(schema)
+          if schema.blank?
+            raise Occi::Core::Errors::CategoryValidationError,
+                  "Schema #{schema.inspect} cannot be blank"
+          end
+          unless schema.end_with?('#')
+            raise Occi::Core::Errors::CategoryValidationError,
+                  "Schema #{schema.inspect} must be terminated with '#'"
+          end
+
+          valid_uri! schema
+          prohibited_chars! schema
+        end
+
+        # Validates given `identifier` as a combination of rules for `term`
+        # and `schema`.
+        #
+        # @example
+        #   valid_identifier? 'http://schema.org/test#a#b' # => false
+        #   valid_identifier? 'http://schema.org/test#a'   # => true
+        #
+        # @param identifier [String] identifier candidate
+        # @return [TrueClass, FalseClass] result
+        def valid_identifier?(identifier)
+          begin
+            valid_identifier! identifier
+          rescue URI::InvalidURIError, Occi::Core::Errors::CategoryValidationError => ex
+            logger.warn "#{self}: Identifier validation failed with #{ex.message}" if respond_to?(:logger)
+            return false
+          end
+
+          true
+        end
+
+        # Similar to `::valid_identifier?`, raises an `Occi::Core::Errors::CategoryValidationError`
+        # error in case of failure.
+        #
+        # @param identifier [String] identifier candidate
+        def valid_identifier!(identifier)
+          elements = identifier.split('#')
+          if elements.count != 2
+            raise Occi::Core::Errors::CategoryValidationError,
+                  "Identifier #{identifier.inspect} is malformed"
+          end
+
+          valid_schema! "#{elements.first}#"
+          valid_term! elements.last
+        end
+
+        # :nodoc:
+        def valid_uri!(uri)
+          URI.split uri
+        end
+
+        # :nodoc:
+        def prohibited_chars!(schema)
+          PROHIBITED_SCHEMA_CHARS.each do |char|
+            raise "Schema #{schema.inspect} contains prohibited character #{char.inspect}" if schema.include?(char)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces instance attribute resetting functionality to
+      # the receiver. Provides methods for applying defaults and
+      # adding attributes on top of existing base attributes.
+      # `base_attributes` and `added_attributes` must be implemented
+      # in the receiver.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module InstanceAttributeResetter
+        # Shorthand for running `reset_attributes` with the `force` flag on.
+        # This method will force defaults from definitions in all available
+        # attributes. No longer defined attributes will be automatically removed.
+        def reset_attributes!
+          reset_attributes true
+        end
+
+        # Shorthand for running `reset_base_attributes` with the `force` flag on.
+        # This method will force defaults from definitions in all available
+        # attributes. No longer defined attributes will be kept unchanged.
+        def reset_base_attributes!
+          reset_base_attributes true
+        end
+
+        # Shorthand for running `reset_added_attributes` with the `force` flag on.
+        # This method will force defaults from definitions in all available
+        # attributes. No longer defined attributes will be kept unchanged.
+        def reset_added_attributes!
+          reset_added_attributes true
+        end
+
+        # Iterates over available attribute definitions and
+        # sets corresponding fields in `attributes`. When using the `force` flag, all
+        # existing attribute values will be replaced by defaults from definitions or
+        # reset to `nil`. No longer defined attributes will be automatically removed.
+        #
+        # @param force [TrueClass, FalseClass] forcibly change attribute values to defaults
+        def reset_attributes(force = false)
+          reset_base_attributes force
+          reset_added_attributes force
+          remove_undef_attributes
+        end
+
+        # Removes attributes (definition and value) if they are no longer defined
+        # for this instance. This is automatically called when invoking reset via
+        # `reset_attributes` or `reset_attributes!`, in all other cases it has to
+        # be triggered explicitly. Attributes without definitions will be removed
+        # as well.
+        #
+        # @return [Hash] updated attribute hash
+        def remove_undef_attributes
+          name_cache = attribute_names
+          attributes.keep_if { |key, value| name_cache.include?(key) && value && value.attribute_definition }
+        end
+
+        # Collects all available attribute names into a list. Without definitions
+        # or values.
+        #
+        # @return [Array] list available attribute names
+        def attribute_names
+          names = added_attributes.collect(&:keys)
+          names << base_attributes.keys
+          names.flatten!
+          names.compact!
+
+          names
+        end
+
+        # Iterates over available base attribute definitions and
+        # sets corresponding fields in `attributes`. When using the `force` flag, all
+        # existing attribute values will be replaced by defaults from definitions or
+        # reset to `nil`. No longer defined attributes will be kept unchanged.
+        #
+        # @param force [TrueClass, FalseClass] forcibly change attribute values to defaults
+        # @return [Array] list of processed attribute names
+        def reset_base_attributes(force = false)
+          processed_attrs = []
+
+          base_attributes.each_pair do |name, definition|
+            processed_attrs << name
+            reset_attribute(name, definition, force)
+          end
+
+          processed_attrs
+        end
+
+        # Iterates over available added attribute definitions and
+        # sets corresponding fields in `attributes`. When using the `force` flag, all
+        # existing attribute values will be replaced by defaults from definitions or
+        # reset to `nil`. No longer defined attributes will be kept unchanged.
+        #
+        # @param force [TrueClass, FalseClass] forcibly change attribute values to defaults
+        # @return [Array] list of processed attribute names
+        def reset_added_attributes(force = false)
+          processed_attrs = []
+
+          added_attributes.each do |attrs|
+            attrs.each_pair do |name, definition|
+              if processed_attrs.include?(name)
+                raise Occi::Core::Errors::AttributeDefinitionError,
+                      "Attribute #{name.inspect} already modified by another mixin"
+              end
+              processed_attrs << name
+              reset_attribute(name, definition, force)
+            end
+          end
+
+          processed_attrs
+        end
+
+        # Sets corresponding attribute fields in `attributes`. When using the `force` flag, any
+        # existing attribute value will be replaced by the default from its definition or
+        # reset to `nil`.
+        #
+        # @param name [String] attribute name
+        # @param definition [AttributeDefinition] attribute definition
+        # @param force [TrueClass, FalseClass] forcibly change attribute value to default
+        def reset_attribute(name, definition, force)
+          if attributes[name]
+            attributes[name].attribute_definition = definition
+          else
+            attributes[name] = Attribute.new(nil, definition)
+          end
+
+          force ? attributes[name].default! : attributes[name].default
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces instance attributes accessor as a shortcut to
+      # getting to the `attributes` values inside the receiver.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module InstanceAttributesAccessor
+        # :nodoc:
+        def [](key)
+          attribute?(key) ? attributes[key].value : nil
+        end
+
+        # :nodoc:
+        def attribute?(key)
+          !attributes[key].nil?
+        end
+
+        # :nodoc:
+        def []=(key, val)
+          unless attribute?(key)
+            raise Occi::Core::Errors::AttributeDefinitionError, 'Attribute named ' \
+                  "#{key.inspect} has not been defined for #{self}"
+          end
+          attributes[key].value = val
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Occi
+  module Core
+    module Helpers
+      # Introduces location-based capabilities to every receiver
+      # class. Provides methods to access set location value
+      # and generate default locations if necessary.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module Locatable
+        # Returns the location of this instance. Set location
+        # is preferred over the generated one. If no location is known
+        # one is generated from available information specific to
+        # this instance.
+        #
+        # @example
+        #   obj.location # => #<URI::Generic /my_location/>
+        #
+        # @return [URI] instance location
+        def location
+          @location || generate_location
+        end
+
+        # Generates default location based on the already configured
+        # instance attribute(s). Fails if required attributes are not
+        # present.
+        #
+        # @example
+        #   obj.generate_location # => #<URI::Generic /my_location/>
+        #
+        # @return [URI] generated location
+        # @abstract This method MUST be implemented in every 'locatable' class
+        def generate_location
+          raise "Cannot generate default location for #{self.class}, I don't know how"
+        end
+
+        protected :generate_location
+      end
+    end
+  end
+end