Implements the base class for all OCCI resources and links, this class should be treated as an abstracts class and not used directly to create entity instances.
@attr kind [Occi::Core::Kind] entity kind, following OCCI's typing mechanism @attr id [String] entity instance identifier, unique in the given domain @attr location [URI] entity instance location, unique in the given domain @attr title [String] entity instance title @attr attributes [Hash] entity instance attributes @attr mixins [Set] set of mixins associated with this entity instance @attr actions [Set] set of actions associated with this entity instance
@abstract The base class itself should be used as an abstract starting
point when creating custom resources and links.
@author Boris Parak <parak@cesnet.cz>
@see `Occi::Core::Entity`
Constructs an instance with the given information. `kind` is a mandatory argument, the rest will either default to appropriate values or remain `nil`. The `id` attribute will default to a newly generated UUID, see `SecureRandom.uuid` for details.
@example
my_kind = Occi::Core::Kind.new term: 'gnr', schema: 'http://example.org/test#' Entity.new kind: my_kind
@param args [Hash] arguments with entity instance information @option args [Occi::Core::Kind] :kind entity kind, following OCCI's typing mechanism @option args [String] :id entity instance identifier, unique in the given domain @option args [URI] :location entity instance location, unique in the given domain @option args [String] :title entity instance title @option args [Hash] :attributes entity instance attributes @option args [Set] :mixins set of mixins associated with this entity instance @option args [Set] :actions set of actions associated with this entity instance
# File lib/occi/core/entity.rb, line 52 def initialize(args = {}) pre_initialize(args) default_args! args @kind = args.fetch(:kind) @location = args.fetch(:location) @attributes = args.fetch(:attributes) @mixins = args.fetch(:mixins) @actions = args.fetch(:actions) post_initialize(args) end
Shorthand for assigning mixins and actions to entity instances. Unsupported `object` types will raise an error. `self` is always returned for chaining purposes.
@example
entity << mixin #=> #<Occi::Core::Entity> entity << action #=> #<Occi::Core::Entity>
@param object [Occi::Core::Mixin, Occi::Core::Action] object to be added @return [Occi::Core::Entity] self
# File lib/occi/core/entity.rb, line 142 def <<(object) case object when Occi::Core::Mixin add_mixin object when Occi::Core::Action add_action object else raise ArgumentError, "Cannot automatically assign #{object.inspect}" end self end
Adds the given action to this instance.
@param action [Occi::Core::Action] action to be added
# File lib/occi/core/entity.rb, line 224 def add_action(action) unless action && kind.actions.include?(action) raise Occi::Core::Errors::MandatoryArgumentError, 'Cannot add an action that is empty or not defined on kind' end actions << action end
Adds the given mixin to this instance. Attributes defined in the mixin will be transfered to instance attributes.
@param mixin [Occi::Core::Mixin] mixin to be added
# File lib/occi/core/entity.rb, line 183 def add_mixin(mixin) unless mixin raise Occi::Core::Errors::MandatoryArgumentError, 'Cannot add a non-existent mixin' end # TODO: handle adding actions mixins << mixin reset_added_attributes end
Collects all available additional attributes for this instance and returns them as an array.
@return [Array] array with added attribute hashes
# File lib/occi/core/entity.rb, line 320 def added_attributes mixins.collect(&:attributes) end
@return [Occi::Core::Mixin, NilClass] filtered mixin
# File lib/occi/infrastructure_ext/monkey_island/entity.rb, line 16 def availability_zone select_mixin Occi::InfrastructureExt::Mixins::AvailabilityZone.new end
@return [Set] filtered mixins
# File lib/occi/infrastructure_ext/monkey_island/entity.rb, line 21 def availability_zones select_mixins Occi::InfrastructureExt::Mixins::AvailabilityZone.new end
Returns all base attributes for this instance in the form of the original hash.
@return [Hash] hash with base attributes
# File lib/occi/core/entity.rb, line 312 def base_attributes kind.attributes end
Disables action identified by `term` on this instance. Unknown actions will NOT raise errors.
@example
entity.disable_action 'start'
@param term [String] action term
# File lib/occi/core/entity.rb, line 259 def disable_action(term) action = actions.detect { |a| a.term == term } return unless action remove_action action end
Enables action identified by `term` on this instance. Actions are looked up in `kind.actions`. Unknown actions will raise errors.
@example
entity.enable_action 'start'
@param term [String] action term
# File lib/occi/core/entity.rb, line 248 def enable_action(term) add_action(kind.actions.detect { |a| a.term == term }) end
@return [String] entity instance identifier, unique in the given domain
# File lib/occi/core/entity.rb, line 66 def id self['occi.core.id'] end
@param id [String] entity instance identifier, unique in the given domain
# File lib/occi/core/entity.rb, line 71 def id=(id) self['occi.core.id'] = id end
Returns entity instance identifier. If such identifier is not set, it will generate a pseudo-random UUID and assign/return it.
@return [String] entity instance identifier
# File lib/occi/core/entity.rb, line 328 def identify! self.id ||= SecureRandom.uuid end
Assigns new kind instance to this entity instance. This method will trigger a complete reset on all previously set attributes, for the sake of consistency.
@param kind [Occi::Core::Kind] kind instance to be assigned @return [Occi::Core::Kind] assigned kind instance
# File lib/occi/core/entity.rb, line 100 def kind=(kind) unless kind raise Occi::Core::Errors::InstanceValidationError, 'Missing valid kind' end @kind = kind reset_attributes! kind end
Short-hand for accessing the identifier of assigned `Kind` instance.
@return [String] identifier of the included `Kind` instance @return [NilClass] if no kind is present
# File lib/occi/core/entity.rb, line 90 def kind_identifier kind ? kind.identifier : nil end
Assigns new mixins instance to this entity instance. This method will trigger a complete reset on all previously set attributes, for the sake of consistency.
@param kind [Hash] mixins instance to be assigned @return [Hash] mixins instance assigned
# File lib/occi/core/entity.rb, line 118 def mixins=(mixins) unless mixins raise Occi::Core::Errors::InstanceValidationError, 'Missing valid mixins' end @mixins = mixins reset_added_attributes! remove_undef_attributes # TODO: handle sync'ing actions mixins end
@return [Occi::Core::Mixin, NilClass] filtered mixin
# File lib/occi/infrastructure_ext/monkey_island/entity.rb, line 6 def region select_mixin Occi::InfrastructureExt::Mixins::Region.new end
@return [Set] filtered mixins
# File lib/occi/infrastructure_ext/monkey_island/entity.rb, line 11 def regions select_mixins Occi::InfrastructureExt::Mixins::Region.new end
Shorthand for removing mixins and actions from entity instances. Unsupported `object` types will raise an error. `self` is always returned for chaining purposes.
@example
entity.remove mixin #=> #<Occi::Core::Entity> entity.remove action #=> #<Occi::Core::Entity>
@param object [Occi::Core::Mixin, Occi::Core::Action] object to be removed @return [Occi::Core::Entity] self
# File lib/occi/core/entity.rb, line 166 def remove(object) case object when Occi::Core::Mixin remove_mixin object when Occi::Core::Action remove_action object else raise ArgumentError, "Cannot automatically remove #{object.inspect}" end self end
Removes the given action from this instance.
@param action [Occi::Core::Action] action to be removed
# File lib/occi/core/entity.rb, line 234 def remove_action(action) unless action raise Occi::Core::Errors::MandatoryArgumentError, 'Cannot remove a non-existent action' end actions.delete action end
Removes the given mixin from this instance. Attributes defined in the mixin will be reset to their original definition or removed completely if not defined as part of `kind` attributes.
@param mixin [Occi::Core::Mixin] mixin to be removed
# File lib/occi/core/entity.rb, line 199 def remove_mixin(mixin) unless mixin raise Occi::Core::Errors::MandatoryArgumentError, 'Cannot remove a non-existent mixin' end # TODO: handle removing actions mixins.delete mixin reset_attributes end
Replaces the given mixin in this instance with a new mixin provided. This is a shorthand for invoking `remove_mixin` and `add_mixin`.
@param old_mixin [Occi::Core::Mixin] mixin to be removed @param new_mixin [Occi::Core::Mixin] mixin to be added
# File lib/occi/core/entity.rb, line 215 def replace_mixin(old_mixin, new_mixin) # TODO: handle replacing actions remove_mixin old_mixin add_mixin new_mixin end
@return [String] entity instance title
# File lib/occi/core/entity.rb, line 76 def title self['occi.core.title'] end
@param title [String] entity instance title
# File lib/occi/core/entity.rb, line 81 def title=(title) self['occi.core.title'] = title end
Validates the content of this entity instance, including all previously defined OCCI attributes and other required elements. This method provides additional information in messages of raised errors.
@example
entity.valid! #=> #<Occi::Core::Errors::InstanceValidationError> entity.valid! #=> nil
@return [NilClass] when entity instance is valid
# File lib/occi/core/entity.rb, line 297 def valid! %[kind location attributes mixins actions].each do |attr| unless send(attr) raise Occi::Core::Errors::InstanceValidationError, "Missing valid #{attr}" end end attributes.each_pair { |name, attribute| valid_attribute!(name, attribute) } end
Validates the content of this entity instance, including all previously defined OCCI attributes and other required elements. This method limits the information returned to a boolean response.
@example
entity.valid? #=> false entity.valid? #=> true
@return [TrueClass] when entity instance is valid @return [FalseClass] when entity instance is invalid
# File lib/occi/core/entity.rb, line 276 def valid? begin valid! rescue *ERRORS => ex logger.warn "Entity invalid: #{ex.message}" return false end true end