class Occi::Core::Entity

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`

Constants

ERRORS

Attributes

actions[RW]
attributes[RW]
kind[RW]
location[W]
mixins[RW]

Public Class Methods

new(args = {}) click to toggle source

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

Public Instance Methods

<<(object) click to toggle source

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
Also aliased as: add
add(object)
Alias for: <<
add_action(action) click to toggle source

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
add_mixin(mixin) click to toggle source

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
added_attributes() click to toggle source

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
availability_zone() click to toggle source

@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
availability_zones() click to toggle source

@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
base_attributes() click to toggle source

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
disable_action(term) click to toggle source

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
enable_action(term) click to toggle source

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
id() click to toggle source

@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
id=(id) click to toggle source

@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
identify!() click to toggle source

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
kind=(kind) click to toggle source

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
kind_identifier() click to toggle source

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
mixins=(mixins) click to toggle source

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
region() click to toggle source

@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
regions() click to toggle source

@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
remove(object) click to toggle source

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
remove_action(action) click to toggle source

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
remove_mixin(mixin) click to toggle source

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
replace_mixin(old_mixin, new_mixin) click to toggle source

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
title() click to toggle source

@return [String] entity instance title

# File lib/occi/core/entity.rb, line 76
def title
  self['occi.core.title']
end
title=(title) click to toggle source

@param title [String] entity instance title

# File lib/occi/core/entity.rb, line 81
def title=(title)
  self['occi.core.title'] = title
end
valid!() click to toggle source

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
valid?() click to toggle source

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