occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/kind.rb

@@ -1,159 +1,127 @@
 module Occi
   module Core
-    class Kind < Occi::Core::Category
-
-      attr_accessor :entities, :parent, :actions
-
-      # @param scheme [String ] The categorisation scheme.
-      # @param term [String] Unique identifier of the Kind instance within the categorisation scheme.
-      # @param title [String] The display name of an instance.
-      # @param parent [Occi::Core::Kind,String] Another Kind instance which this Kind relates to.
-      # @param actions [Occi::Core::Actions,Array] Set of Action instances defined by the Kind instance.
-      # @param location [String] Location of the Kind instance.
-      def initialize(scheme='http://schemas.ogf.org/occi/core#',
-          term='kind',
-          title=nil,
-          attributes=Occi::Core::Attributes.new,
-          parent=nil,
-          actions=Occi::Core::Actions.new,
-          location=nil)
-        super(scheme, term, title, attributes)
-        @parent = [parent].flatten.first
-        @actions = Occi::Core::Actions.new(actions)
-        @entities = Occi::Core::Entities.new
-        @location = location.blank? ? "/#{term}/" : URI.parse(location).path
+    # Defines the classification system of the OCCI Core Model. The `Kind`
+    # instance represents the type identification mechanism for all `Entity`
+    # instances present in the model.
+    #
+    # @example
+    #   Kind.new schema: 'http://schemas.ogf.org/occi/infrastructure#',
+    #            term: 'compute',
+    #            title: 'Compute'
+    #
+    # @attr parent [Kind] previous `Kind` in the OCCI kind hierarchy
+    # @attr actions [Set] list of `Action` instances applicable to this `Kind`
+    # @attr location [URI] protocol agnostic location of this `Kind` instance
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class Kind < Category
+      include Helpers::Locatable
+
+      attr_accessor :parent, :actions
+      attr_writer :location
+
+      # Checks whether the given `Kind` instance is related
+      # to this instance. The given `Kind` instance must be
+      # included in the list of predecessors (see `#related`)
+      # to succeed.
+      #
+      # @param kind [Kind] suspected predecessor
+      # @return [TrueClass, FalseClass] result
+      def related?(kind)
+        return false unless kind
+        return true if kind == self
+        related.include? kind
       end
 
-      # @param scheme [String] The categorisation scheme.
-      # @param term [String] Unique identifier of the Category instance within the categorisation scheme.
-      # @param parent [Array] Another Kind instance which this Kind relates to.
-      # @return [Class] Ruby class with scheme as namespace, term as name and parent kind as super class.
-      def self.get_class(scheme, term, parent=Occi::Core::Entity.kind)
-        parent ||= Occi::Core::Entity.kind
-        raise ArgumentError, 'Mandatory argument cannot be nil' unless scheme && term
-
-        if parent.kind_of? Array
-          parent = parent.first
-        end
-
-        if parent.to_s == 'http://schemas.ogf.org/occi/core#entity'
-          parent = Occi::Core::Entity.kind
-        elsif parent.to_s == 'http://schemas.ogf.org/occi/core#resource'
-          parent = Occi::Core::Resource.kind
-        elsif parent.to_s == 'http://schemas.ogf.org/occi/core#link'
-          parent = Occi::Core::Link.kind
-        elsif parent.kind_of? Occi::Core::Kind
-          parent = parent
-        else
-          parent = self.get_class(*parent.to_s.split('#')).kind
-        end
-
-        term = self.sanitize_term(term) if Occi::Settings.compatibility
-        raise ArgumentError, "Invalid characters in term #{term}" unless Occi::Core::Category.valid_term?(term)
-
-        unless scheme.end_with? '#'
-          scheme << '#'
-        end
-
-        uri = URI.parse(scheme)
-
-        if uri.host == 'schemas.ogf.org'
-          namespace = uri.path.reverse.chomp('/').reverse.split('/')
-        else
-          namespace = uri.host.split('.').reverse + uri.path.reverse.chomp('/').reverse.split('/')
-        end
-        namespace.inject(Object) do |mod, name|
-          if mod.constants.collect { |sym| sym.to_s }.include? name.capitalize
-            namespace = mod.const_get name.capitalize
-          else
-            namespace = mod.const_set name.capitalize, Module.new
-          end
-        end
-
-        class_name = term.classify
-        if namespace.const_defined? class_name
-          klass = namespace.const_get class_name
-          unless klass.ancestors.include? Occi::Core::Entity
-            raise "OCCI Kind with type identifier #{scheme + term} could not be created as the corresponding class #{klass.to_s} already exists and is not derived from Occi::Core::Entity"
-          end
-        else
-          klass = namespace.const_set class_name, Class.new(parent.entity_type)
-          klass.kind = Occi::Core::Kind.new scheme=scheme,
-                                            term=term,
-                                            title=nil,
-                                            attributes={},
-                                            parent=parent
-        end
-
-        klass
+      # Checks whether the given `Kind` instance is related
+      # to this instance. The given `Kind` instance must be
+      # the immediate predecessor (see `#directly_related`)
+      # to succeed.
+      #
+      # @param kind [Kind] suspected predecessor
+      # @return [TrueClass, FalseClass] result
+      def directly_related?(kind)
+        return false unless kind
+        return true if kind == self
+        directly_related.include? kind
       end
 
-      # Check if this Kind instance is related to another Kind instance.
+      # Transitively returns all predecessors of this `Kind` instance in
+      # a multi-element `Array`.
       #
-      # @param kind [Occi::Core::Kind, String] Kind or Type Identifier of a Kind where relation should be checked.
-      # @return [true,false]
-      def related_to?(kind)
-        to_s == kind.to_s || parent.to_s == kind.to_s \
-	  || \
-	(parent.to_s == "http://schemas.ogf.org/occi/infrastructure#network" && kind.to_s == "http://schemas.ogf.org/occi/core#resource") \
-	  || \
-	(parent.to_s == "http://schemas.ogf.org/occi/infrastructure#storage" && kind.to_s == "http://schemas.ogf.org/occi/core#resource") \
-	  || \
-	(parent.to_s == "http://schemas.ogf.org/occi/infrastructure#compute" && kind.to_s == "http://schemas.ogf.org/occi/core#resource")
+      # @return [Array] list containing predecessors of this `Kind` instance
+      def related
+        return directly_related if hierarchy_root?
+        [parent, parent.related].flatten.compact
       end
 
-      def entity_type
-        self.class.get_class self.scheme, self.term, self.parent
+      # For compatibility reasons, returns the parent instance of this `Kind` in
+      # an `Array`. For hierarchy roots, returns only an empty `Array`.
+      #
+      # @return [Array] a list containing the parent `Kind` instance, if any
+      def directly_related
+        [parent].compact
       end
 
-      # set location attribute of kind
-      # @param [String] location
-      def location=(location)
-        location = URI.parse(location).path if location
-        raise "Kind locations must end with a slash!" unless location.blank? || location =~ /^\/\S+\/$/
-        @location = location
+      # Indicates whether this instance is the base of the OCCI kind
+      # hierarchy, i.e. there are no predecessors. This helps to
+      # calculate the relationship status correctly, see `#related`.
+      #
+      # @return [TrueClass, FalseClass] result
+      def hierarchy_root?
+        parent.nil?
       end
 
-      def location
-        @location ? @location.clone : nil
+      protected
+
+      # :nodoc:
+      def defaults
+        super.merge(parent: nil, actions: Set.new, location: nil)
       end
 
-      def related
-        [self.parent]
+      # :nodoc:
+      def sufficient_args!(args)
+        super
+        [:actions].each do |attr|
+          if args[attr].nil?
+            raise Occi::Core::Errors::MandatoryArgumentError, "#{attr} is a mandatory " \
+                  "argument for #{self.class}"
+          end
+        end
       end
 
-      # @param [Hash] options
-      # @return [Hashie::Mash] json representation
-      def as_json(options={})
-        kind = Hashie::Mash.new
-        kind.parent = self.parent.to_s if self.parent
-        kind.related = self.related.join(' ').split(' ') if self.related.any?
-        kind.actions = self.actions.join(' ').split(' ') if self.actions.any?
-        kind.location = self.location if self.location
-        kind.merge! super
-        kind
+      # :nodoc:
+      def post_initialize(args)
+        super
+        @parent = args.fetch(:parent)
+        @actions = args.fetch(:actions)
+        @location = args.fetch(:location)
+
+        load_parent_attributes! if parent
       end
 
-      # @return [String] string representation of the kind
-      def to_string
-        string = super
-        string << ";rel=#{self.related.first.to_s.inspect}" if self.related.any?
-        string << ";location=#{self.location.inspect}"
-        string << self.attributes.to_string_short
-        string << ";actions=#{self.actions.join(' ').inspect}" if self.actions.any?
-        string
+      # :nodoc:
+      def load_parent_attributes!
+        attributes.merge!(parent.attributes) { |_, oldval, _| oldval }
       end
 
       private
 
-      # Relaxed parser rules require additional checks on terms.
-      def self.sanitize_term(term)
-        sanitized = term.downcase.gsub(/[^a-z0-9-]/, '_').gsub(/_+/, '_').gsub(/^_|_$/, '')
-        sanitized = "uuid_#{sanitized}" if sanitized.match(/^[0-9]/)
-
-        sanitized
+      # Generates default location based on the already configured
+      # `term` attribute. Fails if `term` is not present.
+      #
+      # @example
+      #   kind.term              # => 'compute'
+      #   kind.generate_location # => #<URI::Generic /compute/>
+      #
+      # @return [URI] generated location
+      def generate_location
+        if term.blank?
+          raise Occi::Core::Errors::MandatoryArgumentError,
+                'Cannot generate default location without a `term`'
+        end
+        URI.parse "/#{term}/"
       end
-
     end
   end
 end

data/lib/occi/core/link.rb

@@ -1,95 +1,70 @@
 module Occi
   module Core
-    class Link < Occi::Core::Entity
-
-      attr_accessor :rel, :source, :target
-
-      self.attributes = Occi::Core::Attributes.new(Occi::Core::Entity.attributes)
-      self.attributes['occi.core.target'] = {:mutable => true}
-      self.attributes['occi.core.source'] = {:mutable => true, :required => true}
-
-      self.kind = Occi::Core::Kind.new scheme='http://schemas.ogf.org/occi/core#',
-                                       term='link',
-                                       title='link',
-                                       attributes=Occi::Core::Attributes.new(self.attributes),
-                                       parent=Occi::Core::Entity.kind
+    # Implements the base class for all OCCI links, this
+    # class can be used directly to create link instances.
+    #
+    # @attr source [URI] link source as URI
+    # @attr source_kind [Occi::Core::Kind, NilClass] source kind or `nil` if unknown
+    # @attr target [URI] link target, may point outside of this domain
+    # @attr target_kind [Occi::Core::Kind, NilClass] target kind or `nil` if ourside the domain
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class Link < Entity
+      attr_accessor :target_kind, :source_kind
+
+      # @return [URI] link source
+      def source
+        self['occi.core.source']
+      end
 
-      # @param [String] kind
-      # @param [String] mixins
-      # @param [Occi::Core::Attributes] attributes
-      # @param [Array] actions
-      # @param [String] rel
-      # @param [String,Occi::Core::Entity] target
-      # @param [String,Occi::Core::Entity] source
-      def initialize(kind=self.kind, mixins=[], attributes={}, actions=[], rel=Occi::Core::Link.type_identifier, target=nil, source=nil, location=nil)
-        super(kind, mixins, attributes, actions, location)
-        scheme, term = rel.to_s.split('#')
-        @rel = Occi::Core::Kind.get_class(scheme, term).kind if scheme && term
-        @source = source if source
-        @target = target
+      # @param source [URI] link source
+      def source=(source)
+        self['occi.core.source'] = source.is_a?(String) ? URI.parse(source) : source
       end
 
-      # @return [String] target attribute of the link
+      # @return [URI] link target
       def target
-        @target ||= self.attributes.occi_.core_.target
-        @target
+        self['occi.core.target']
       end
 
-      # set target attribute of link
-      # @param [String] target
+      # @param target [URI] link target
       def target=(target)
-        self.attributes['occi.core.target'] = target.to_s
-        @target = target.to_s
+        self['occi.core.target'] = target.is_a?(String) ? URI.parse(target) : target
       end
 
-      # @return [String] source attribute of the link
-      def source
-        @source ||= self.attributes.occi_.core_.source
-        @source
-      end
+      # See `target_kind`
+      alias rel target_kind
+      alias rel= target_kind=
 
-      # set source attribute of link
-      # @param [String] source
-      def source=(source)
-        self.attributes['occi.core.source'] = source.to_s
-        @source = source.to_s
-      end
+      # See `#valid!` on `Occi::Core::Entity`.
+      def valid!
+        %i[source target].each do |attr|
+          next if send(attr)
+          raise Occi::Core::Errors::InstanceValidationError, "Missing valid #{attr}"
+        end
 
-      # Runs check on attributes
-      def check(set_defaults = false)
-        raise ArgumentError, "Cannot run check on #{self.to_s.inspect} kind #{self.kind.to_s.inspect} without relation (the rel attribute) set!" unless @rel
         super
       end
 
-      # @param [Hash] options
-      # @return [Hashie::Mash] json representation
-      def as_json(options={})
-        link = super
-        link.rel = @rel.to_s if @rel
-        link.source = self.source.to_s unless self.source.to_s.blank?
-        link.target = self.target.to_s if self.target
-        link
-      end
-
-      # @return [String] text representation of link reference
-      def to_string
-        string = "<#{self.target.to_s}>"
-        string << ";rel=#{@rel.to_s.inspect}"
-        string << ";self=#{self.location.inspect}" if self.location
+      protected
 
-        categories = [@kind.type_identifier].concat(@mixins.to_a.collect { |m| m.type_identifier })
-        string << ";category=#{categories.join(' ').inspect}"
-
-        string << @attributes.to_string
-
-        string
+      # :nodoc:
+      def defaults
+        super.merge(source: nil, target: nil, target_kind: nil, source_kind: nil)
       end
 
-      # @return [String] text representation of link
-      def to_text_link
-        "Link: #{self.to_string}"
+      # :nodoc:
+      def post_initialize(args)
+        super
+        if attributes['occi.core.source']
+          self.source = args.fetch(:source)
+          @source_kind = args.fetch(:source_kind)
+        end
+
+        return unless attributes['occi.core.target']
+        self.target = args.fetch(:target)
+        @target_kind = args.fetch(:target_kind)
       end
-
     end
   end
 end

data/lib/occi/core/mixin.rb

@@ -1,81 +1,96 @@
 module Occi
   module Core
-    class Mixin < Occi::Core::Category
+    # Defines the extension mechanism of the OCCI Core Model. The
+    # `Mixin` instance can be used to add `actions`, `attributes`,
+    # and custom features to existing `Entity` instances based on
+    # a specific `Kind` instance. A `Mixin` instance may depend
+    # on other `Mixin` instances (see `#depends`) and may be applied
+    # only to `Entity` instances based on specified `Kind` instances
+    # (see `#applies`). Some `Mixin` instances have special meaning
+    # defined in OCCI Standard documents.
+    #
+    # @attr actions [Set] list of `Action` instances attached to this mixin instance
+    # @attr depends [Set] list of `Mixin` instances on which this mixin depends
+    # @attr applies [Set] list of `Kind` instances to which this mixin can be applied
+    # @attr location [URI] protocol agnostic location of this mixin instance
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class Mixin < Category
+      include Helpers::Locatable
 
-      attr_accessor :entities, :depends, :actions, :applies
+      attr_accessor :actions, :depends, :applies
+      attr_writer :location
 
-      # @param [String] scheme
-      # @param [String] term
-      # @param [String] title
-      # @param [Occi::Core::Attributes,Hash,NilClass] attributes
-      # @param [Occi::Core::Categories,Hash,NilClass] depends
-      # @param [Occi::Core::Actions,Hash,NilClass] actions
-      # @param [String] location
-      # @param [Occi::Core::Kinds, NilClass] applies
-      def initialize(scheme='http://schemas.ogf.org/occi/core#',
-          term='mixin',
-          title=nil,
-          attributes=Occi::Core::Attributes.new,
-          depends=Occi::Core::Dependencies.new,
-          actions=Occi::Core::Actions.new,
-          location='',
-          applies=Occi::Core::Kinds.new)
-
-        super(scheme, term, title, attributes)
-        @depends = Occi::Core::Dependencies.new depends
-        @actions = Occi::Core::Actions.new actions
-        @entities = Occi::Core::Entities.new
-        @location = location.blank? ? "/mixin/#{term}/" : URI.parse(location).path
-        @applies = Occi::Core::Kinds.new applies
+      # Checks whether the given mixin is in the dependency
+      # chains of this instance. Checking for dependencies
+      # is strictly flat (no transitivity is applied). One
+      # `Mixin` instance may depend on multiple other instances.
+      #
+      # @param mixin [Mixin] candidate instance
+      # @return [TrueClass, FalseClass] result
+      def depends?(mixin)
+        return false unless depends && mixin
+        depends.include? mixin
       end
 
-      # Check if this Mixin instance is related to another Mixin instance.
+      # Checks whether the given kind is in the applies
+      # set of this instance (i.e., this mixin can be applied
+      # to an `Entity` instance of the given kind). Checking
+      # for applicable kinds is strictly flat (no transitivity
+      # is applied). One `Mixin` instance may be applied to
+      # multiple kinds (`Entity` instances of the given kind).
       #
-      # @param kind [Occi::Core::Mixin, String] Mixin or Type Identifier of a Mixin where relation should be checked.
-      # @return [true,false]
-      def related_to?(mixin)
-        self.to_s == mixin.to_s || self.related.any? { |m| m.type_identifier == mixin.to_s }
+      # @param kind [Kind] candidate instance
+      # @return [TrueClass, FalseClass] result
+      def applies?(kind)
+        return false unless applies && kind
+        applies.include? kind
       end
 
-      # set location attribute of kind
-      # @param [String] location
-      def location=(location)
-        location = URI.parse(location).path if location
-        raise "Mixin locations must end with a slash!" unless location.blank? || location =~ /^\/\S+\/$/
-        @location = location
-      end
+      protected
 
-      def location
-        @location ? @location.clone : nil
+      # :nodoc:
+      def defaults
+        super.merge(actions: Set.new, depends: Set.new, applies: Set.new, location: nil)
       end
 
-      def related
-        self.depends.to_a
+      # :nodoc:
+      def sufficient_args!(args)
+        super
+        %i[actions depends applies].each do |attr|
+          if args[attr].nil?
+            raise Occi::Core::Errors::MandatoryArgumentError, "#{attr} is a mandatory " \
+                  "argument for #{self.class}"
+          end
+        end
       end
 
-      # @param [Hash] options
-      # @return [Hashie::Mash] json representation
-      def as_json(options={})
-        mixin = Hashie::Mash.new
-        mixin.depends = self.depends.to_a.collect { |m| m.type_identifier } if self.depends.any?
-        mixin.applies = self.applies.to_a.collect { |m| m.type_identifier } if self.applies.any?
-        mixin.related = self.related.to_a.collect { |m| m.type_identifier } if self.related.any?
-        mixin.actions = self.actions if self.actions.any?
-        mixin.location = self.location if self.location
-        mixin.merge! super
-        mixin
+      # :nodoc:
+      def post_initialize(args)
+        super
+        @actions = args.fetch(:actions)
+        @depends = args.fetch(:depends)
+        @applies = args.fetch(:applies)
+        @location = args.fetch(:location)
       end
 
-      # @return [String] text representation
-      def to_string
-        string = super
-        string << ";rel=#{self.related.join(' ').inspect}" if self.related.any?
-        string << ";location=#{self.location.inspect}"
-        string << self.attributes.to_string_short
-        string << ";actions=#{self.actions.join(' ').inspect}" if self.actions.any?
-        string
-      end
+      private
 
+      # Generates default location based on the already configured
+      # `term` attribute. Fails if `term` is not present.
+      #
+      # @example
+      #   mixin.term              # => 'compute'
+      #   mixin.generate_location # => #<URI::Generic /mixin/compute/>
+      #
+      # @return [URI] generated location string
+      def generate_location
+        if term.blank?
+          raise Occi::Core::Errors::MandatoryArgumentError,
+                'Cannot generate default location without a `term`'
+        end
+        URI.parse "/mixin/#{term}/"
+      end
     end
   end
 end