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



53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/occi/core/entity.rb', line 53

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

#actions ⇒ Set

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

#attributes ⇒ Hash

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

#id ⇒ String

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

#kind ⇒ Occi::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

#location ⇒ URI

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

#mixins ⇒ Set

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

#title ⇒ String

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:



143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/occi/core/entity.rb', line 143

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:



225
226
227
228
229
230
 
# File 'lib/occi/core/entity.rb', line 225

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:



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/occi/core/entity.rb', line 184

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 ⇒ Array

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

Returns:

  • (Array) —

    array with added attribute hashes



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

def added_attributes
  mixins.collect(&:attributes)
end

#availability_zone ⇒ Occi::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_zones ⇒ Set

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_attributes ⇒ Hash

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

Returns:

  • (Hash) —

    hash with base attributes



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

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



260
261
262
263
264
 
# File 'lib/occi/core/entity.rb', line 260

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



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

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



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

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

#kind_identifier ⇒ String, 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



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

def kind_identifier
  kind ? kind.identifier : nil
end

#region ⇒ Occi::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

#regions ⇒ Set

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:



167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/occi/core/entity.rb', line 167

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:



235
236
237
238
239
240
 
# File 'lib/occi/core/entity.rb', line 235

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:



200
201
202
203
204
205
206
207
208
209
 
# File 'lib/occi/core/entity.rb', line 200

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:



216
217
218
219
220
 
# File 'lib/occi/core/entity.rb', line 216

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



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

def valid!
  i[kind 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



277
278
279
280
281
282
283
284
285
286
 
# File 'lib/occi/core/entity.rb', line 277

def valid?
  begin
    valid!
  rescue *ERRORS => ex
    logger.warn "Entity invalid: #{ex.message}"
    return false
  end

  true
end