Class: Occi::Core::Entity

Inherits:
Object
  • Object
show all
Includes:
Helpers::ArgumentValidator, Helpers::InstanceAttributeResetter, Helpers::InstanceAttributesAccessor, Helpers::Locatable, Helpers::MixinSelector, Helpers::Renderable, Yell::Loggable
Defined in:
lib/occi/core/entity.rb,
lib/occi/infrastructure_ext/monkey_island/entity.rb

Overview

See Also:

  • `Occi`Occi::Core`Occi::Core::Entity`

Direct Known Subclasses

Link, Resource

Constant Summary collapse

ERRORS =
[
  Occi::Core::Errors::AttributeValidationError, Occi::Core::Errors::AttributeDefinitionError,
  Occi::Core::Errors::InstanceValidationError
].freeze

Constants included from Helpers::Renderable

Helpers::Renderable::RENDERER_FACTORY_CLASS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers::MixinSelector

#dependent_term, #dependent_term!, #dependent_terms, #select_mixin, #select_mixin!, #select_mixins

Methods included from Helpers::InstanceAttributeResetter

#attribute_names, #remove_undef_attributes, #reset_added_attributes, #reset_added_attributes!, #reset_attribute, #reset_attributes, #reset_attributes!, #reset_base_attributes, #reset_base_attributes!

Methods included from Helpers::InstanceAttributesAccessor

#[], #[]=, #attribute?

Methods included from Helpers::Renderable

extended, included, #render, #renderer_factory, renderer_factory, renderer_factory_class, #renderer_for

Constructor Details

#initialize(args = {}) ⇒ 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.

Examples:

my_kind = Occi::Core::Kind.new term: 'gnr', schema: 'http://example.org/test#'
Entity.new kind: my_kind

Parameters:

  • args (Hash) (defaults to: {})

    arguments with entity instance information

Options Hash (args):

  • :kind (Occi::Core::Kind)

    entity kind, following OCCI's typing mechanism

  • :id (String)

    entity instance identifier, unique in the given domain

  • :location (URI)

    entity instance location, unique in the given domain

  • :title (String)

    entity instance title

  • :attributes (Hash)

    entity instance attributes

  • :mixins (Set)

    set of mixins associated with this entity instance

  • :actions (Set)

    set of actions associated with this entity instance


52
53
54
55
56
57
58
59
60
61
62
63
# 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

Instance Attribute Details

#actionsSet

set of actions associated with this entity instance

Returns:

  • (Set)

    the current value of actions


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def actions
  @actions
end

#attributesHash

entity instance attributes

Returns:

  • (Hash)

    the current value of attributes


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def attributes
  @attributes
end

#idString

Returns entity instance identifier, unique in the given domain.

Returns:

  • (String)

    entity instance identifier, unique in the given domain


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def id
  @id
end

#kindOcci::Core::Kind

entity kind, following OCCI's typing mechanism

Returns:


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def kind
  @kind
end

#locationURI

entity instance location, unique in the given domain

Returns:

  • (URI)

    the current value of location


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def location
  @location
end

#mixinsSet

set of mixins associated with this entity instance

Returns:

  • (Set)

    the current value of mixins


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def mixins
  @mixins
end

#titleString

Returns entity instance title.

Returns:

  • (String)

    entity instance title


18
19
20
# File 'lib/occi/core/entity.rb', line 18

def title
  @title
end

Instance Method Details

#<<(object) ⇒ Occi::Core::Entity Also known as: add

Shorthand for assigning mixins and actions to entity instances. Unsupported `object` types will raise an error. `self` is always returned for chaining purposes.

Examples:

entity << mixin   #=> #<Occi::Core::Entity>
entity << action  #=> #<Occi::Core::Entity>

Parameters:

Returns:


142
143
144
145
146
147
148
149
150
151
152
153
# 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

#add_action(action) ⇒ Object

Adds the given action to this instance.

Parameters:


224
225
226
227
228
229
# 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) ⇒ Object

Adds the given mixin to this instance. Attributes defined in the mixin will be transfered to instance attributes.

Parameters:


183
184
185
186
187
188
189
190
191
192
# 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_attributesArray

Collects all available additional attributes for this instance and returns them as an array.

Returns:

  • (Array)

    array with added attribute hashes


320
321
322
# File 'lib/occi/core/entity.rb', line 320

def added_attributes
  mixins.collect(&:attributes)
end

#availability_zoneOcci::Core::Mixin, NilClass

Returns filtered mixin.

Returns:


16
17
18
# File 'lib/occi/infrastructure_ext/monkey_island/entity.rb', line 16

def availability_zone
  select_mixin Occi::InfrastructureExt::Mixins::AvailabilityZone.new
end

#availability_zonesSet

Returns filtered mixins.

Returns:

  • (Set)

    filtered mixins


21
22
23
# File 'lib/occi/infrastructure_ext/monkey_island/entity.rb', line 21

def availability_zones
  select_mixins Occi::InfrastructureExt::Mixins::AvailabilityZone.new
end

#base_attributesHash

Returns all base attributes for this instance in the form of the original hash.

Returns:

  • (Hash)

    hash with base attributes


312
313
314
# File 'lib/occi/core/entity.rb', line 312

def base_attributes
  kind.attributes
end

#disable_action(term) ⇒ Object

Disables action identified by `term` on this instance. Unknown actions will NOT raise errors.

Examples:

entity.disable_action 'start'

Parameters:

  • term (String)

    action term


259
260
261
262
263
# 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) ⇒ Object

Enables action identified by `term` on this instance. Actions are looked up in `kind.actions`. Unknown actions will raise errors.

Examples:

entity.enable_action 'start'

Parameters:

  • term (String)

    action term


248
249
250
# File 'lib/occi/core/entity.rb', line 248

def enable_action(term)
  add_action(kind.actions.detect { |a| a.term == term })
end

#identify!String

Returns entity instance identifier. If such identifier is not set, it will generate a pseudo-random UUID and assign/return it.

Returns:

  • (String)

    entity instance identifier


328
329
330
# File 'lib/occi/core/entity.rb', line 328

def identify!
  self.id ||= SecureRandom.uuid
end

#kind_identifierString, NilClass

Short-hand for accessing the identifier of assigned `Kind` instance.

Returns:

  • (String)

    identifier of the included `Kind` instance

  • (NilClass)

    if no kind is present


90
91
92
# File 'lib/occi/core/entity.rb', line 90

def kind_identifier
  kind ? kind.identifier : nil
end

#regionOcci::Core::Mixin, NilClass

Returns filtered mixin.

Returns:


6
7
8
# File 'lib/occi/infrastructure_ext/monkey_island/entity.rb', line 6

def region
  select_mixin Occi::InfrastructureExt::Mixins::Region.new
end

#regionsSet

Returns filtered mixins.

Returns:

  • (Set)

    filtered mixins


11
12
13
# File 'lib/occi/infrastructure_ext/monkey_island/entity.rb', line 11

def regions
  select_mixins Occi::InfrastructureExt::Mixins::Region.new
end

#remove(object) ⇒ Occi::Core::Entity

Shorthand for removing mixins and actions from entity instances. Unsupported `object` types will raise an error. `self` is always returned for chaining purposes.

Examples:

entity.remove mixin   #=> #<Occi::Core::Entity>
entity.remove action  #=> #<Occi::Core::Entity>

Parameters:

Returns:


166
167
168
169
170
171
172
173
174
175
176
177
# 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) ⇒ Object

Removes the given action from this instance.

Parameters:


234
235
236
237
238
239
# 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) ⇒ Object

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.

Parameters:


199
200
201
202
203
204
205
206
207
208
# 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) ⇒ Object

Replaces the given mixin in this instance with a new mixin provided. This is a shorthand for invoking `remove_mixin` and `add_mixin`.

Parameters:


215
216
217
218
219
# 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

#valid!NilClass

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.

Examples:

entity.valid! #=> #<Occi::Core::Errors::InstanceValidationError>
entity.valid! #=> nil

Returns:

  • (NilClass)

    when entity instance is valid


297
298
299
300
301
302
303
304
305
306
# File 'lib/occi/core/entity.rb', line 297

def valid!
  %i[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?TrueClass, FalseClass

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.

Examples:

entity.valid? #=> false
entity.valid? #=> true

Returns:

  • (TrueClass)

    when entity instance is valid

  • (FalseClass)

    when entity instance is invalid


276
277
278
279
280
281
282
283
284
285
# 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