class SoftLayer::Software

Each SoftLayer Software instance provides information about software installed on a specific piece of hardware.

This class roughly corresponds to the entity SoftLayer_Software_Component in the API.

Attributes

manufacturer_activation_code[R]

The manufacturer code that is needed to activate a license.

manufacturer_license_key[R]

A license key for this specific installation of software, if it is needed.

Public Class Methods

find_software_on_hardware(options_hash = {}) click to toggle source

Retrieve a list of software from hardware devices.

The options parameter should contain:

:client - The client used to connect to the API

If no client is given, then the routine will try to use SoftLayer::Client.default_client If no client can be found the routine will raise an error.

You may filter the list returned by adding options:

  • :datacenter (string/array) - Include software from hardware matching this datacenter

  • :description (string/array) - Include software that matches this description

  • :domain (string/array) - Include software from hardware matching this domain

  • :hardware_type (symbol) - Include software from hardware matching this hardware type

  • :hostname (string/array) - Include software from hardware matching this hostname

  • :manufacturer (string/array) - Include software that matches this manufacturer

  • :name (string/array) - Include software that matches this name

  • :username (string/array) - Include software that has software password matching this username

You may use the following properties to provide hardware or software object filter instances:

  • :hardware_object_filter (ObjectFilter) - Include software from hardware that matches the criteria of this object filter

  • :software_object_filter (ObjectFilter) - Include software that matches the criteria of this object filter

  • :software_object_mask (string) - Include software properties that matches the criteria of this object mask

# File lib/softlayer/Software.rb, line 150
def self.find_software_on_hardware(options_hash = {})
  softlayer_client = options_hash[:client] || Client.default_client
  raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client

  if(options_hash.has_key? :hardware_object_filter)
    hardware_object_filter = options_hash[:hardware_object_filter]
    raise "Expected an instance of SoftLayer::ObjectFilter" unless hardware_object_filter.kind_of?(SoftLayer::ObjectFilter)
  else
    hardware_object_filter = ObjectFilter.new()
  end

  if(options_hash.has_key? :software_object_filter)
    software_object_filter = options_hash[:software_object_filter]
    raise "Expected an instance of SoftLayer::ObjectFilter" unless software_object_filter.kind_of?(SoftLayer::ObjectFilter)
  else
    software_object_filter = ObjectFilter.new()
  end

  filter_label = {
    :bare_metal_instance => "bareMetalInstances",
    :hardware            => "hardware",
    :network_hardware    => "networkHardware",
    :router              => "routers"
  }

  option_to_filter_path = {
    :hardware       => {
      :datacenter     => lambda { |hardware_type| return [ filter_label[hardware_type], '.datacenter.name' ].join        },
      :domain         => lambda { |hardware_type| return [ filter_label[hardware_type], '.domain' ].join                 },
      :hostname       => lambda { |hardware_type| return [ filter_label[hardware_type], '.hostname' ].join               },
      :tags           => lambda { |hardware_type| return [ filter_label[hardware_type], '.tagReferences.tag.name' ].join }
    },
    :software       => {
      :description  => "softwareComponents.softwareDescription.longDescription",
      :manufacturer => "softwareComponents.softwareDescription.manufacturer",
      :name         => "softwareComponents.softwareDescription.name",
      :username     => "softwareComponents.passwords.username"
    }
  }

  if options_hash[:hardware_type]
    unless filter_label.keys.include?(options_hash[:hardware_type])
      raise "Expected :bare_metal_instance, :hardware, :network_hardware, or :router for option :hardware_type in #{__method__}"
    end
  end

  option_to_filter_path[:hardware].keys.each do |option|
    if options_hash[option]
      hardware_object_filter.modify { |filter| filter.accept(option_to_filter_path[:hardware][option].call(options_hash[:hardware_type] || :hardware)).when_it is(options_hash[option]) }
    end
  end

  option_to_filter_path[:software].each do |option, filter_path|
    software_object_filter.modify { |filter| filter.accept(filter_path).when_it is(options_hash[option]) } if options_hash[option]
  end

  account_service = softlayer_client[:Account]
  account_service = account_service.object_filter(hardware_object_filter) unless hardware_object_filter.empty?
  account_service = account_service.object_mask("mask[id]")

  case options_hash[:hardware_type]
  when :bare_metal_instance
    hardware_data = account_service.getBareMetalInstances
  when :hardware, nil
    hardware_data = account_service.getHardware
  when :network_hardware
    hardware_data = account_service.getNetworkHardware
  when :router
    hardware_data = account_service.getRouters
  end

  software = hardware_data.collect do |hardware|
    hardware_service = softlayer_client[:Hardware].object_with_id(hardware['id'])
    hardware_service = hardware_service.object_filter(software_object_filter) unless software_object_filter.empty?
    hardware_service = hardware_service.object_mask(Software.default_object_mask)
    hardware_service = hardware_service.object_mask(options_hash[:software_object_mask]) if options_hash[:software_object_mask]

    software_data = hardware_service.getSoftwareComponents
    software_data.map { |software| Software.new(softlayer_client, software) unless software.empty? }.compact
  end

  software.flatten
end
find_software_on_virtual_servers(options_hash = {}) click to toggle source

Retrieve a list of software from virtual servers.

The options parameter should contain:

:client - The client used to connect to the API

If no client is given, then the routine will try to use SoftLayer::Client.default_client If no client can be found the routine will raise an error.

You may filter the list returned by adding options:

  • :datacenter (string/array) - Include software from virtual servers matching this datacenter

  • :description (string/array) - Include software that matches this description

  • :domain (string/array) - Include software from virtual servers matching this domain

  • :hostname (string/array) - Include software from virtual servers matching this hostname

  • :manufacturer (string/array) - Include software that matches this manufacturer

  • :name (string/array) - Include software that matches this name

  • :username (string/array) - Include software that has software password matching this username

You may use the following properties to provide virtual server or software object filter instances:

  • :virtual_server_object_filter (ObjectFilter) - Include software from virtual servers that matches the criteria of this object filter

  • :software_object_filter (ObjectFilter) - Include software that matches the criteria of this object filter

  • :software_object_mask (string) - Include software properties that matches the criteria of this object mask

# File lib/softlayer/Software.rb, line 258
def self.find_software_on_virtual_servers(options_hash = {})
  softlayer_client = options_hash[:client] || Client.default_client
  raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client

  if(options_hash.has_key? :virtual_server_object_filter)
    virtual_server_object_filter = options_hash[:virtual_server_object_filter]
    raise "Expected an instance of SoftLayer::ObjectFilter" unless virtual_server_object_filter.kind_of?(SoftLayer::ObjectFilter)
  else
    virtual_server_object_filter = ObjectFilter.new()
  end

  if(options_hash.has_key? :software_object_filter)
    software_object_filter = options_hash[:software_object_filter]
    raise "Expected an instance of SoftLayer::ObjectFilter" unless software_object_filter.kind_of?(SoftLayer::ObjectFilter)
  else
    software_object_filter = ObjectFilter.new()
  end

  option_to_filter_path = {
    :software       => {
      :description  => "softwareComponents.softwareDescription.longDescription",
      :manufacturer => "softwareComponents.softwareDescription.manufacturer",
      :name         => "softwareComponents.softwareDescription.name",
      :username     => "softwareComponents.passwords.username"
    },
    :virtual_server => {
      :datacenter   => "virtualGuests.datacenter.name",
      :domain       => "virtualGuests.domain",
      :hostname     => "virtualGuests.hostname",
      :tags         => "virtualGuests.tagReferences.tag.name"
    }
  }

  option_to_filter_path[:virtual_server].each do |option, filter_path|
    virtual_server_object_filter.modify { |filter| filter.accept(filter_path).when_it is(options_hash[option]) } if options_hash[option]
  end

  option_to_filter_path[:software].each do |option, filter_path|
    software_object_filter.modify { |filter| filter.accept(filter_path).when_it is(options_hash[option]) } if options_hash[option]
  end

  account_service = softlayer_client[:Account]
  account_service = account_service.object_filter(virtual_server_object_filter) unless virtual_server_object_filter.empty?
  account_service = account_service.object_mask("mask[id]")

  virtual_server_data = account_service.getVirtualGuests

  software = virtual_server_data.collect do |virtual_server|
    virtual_server_service = softlayer_client[:Virtual_Guest].object_with_id(virtual_server['id'])
    virtual_server_service = virtual_server_service.object_filter(software_object_filter) unless software_object_filter.empty?
    virtual_server_service = virtual_server_service.object_mask(Software.default_object_mask)
    virtual_server_service = virtual_server_service.object_mask(options_hash[:software_object_mask]) if options_hash[:software_object_mask]

    software_data = virtual_server_service.getSoftwareComponents
    software_data.map { |software| Software.new(softlayer_client, software) unless software.empty? }.compact
  end

  software.flatten
end

Protected Class Methods

default_object_mask() click to toggle source
# File lib/softlayer/Software.rb, line 343
def self.default_object_mask
  {
    "mask(SoftLayer_Software_Component)" => [
                                             'id',
                                             'manufacturerActivationCode',
                                             'manufacturerLicenseInstance'
                                            ]
  }.to_sl_object_mask
end

Public Instance Methods

add_user_password(username, password, options = {}) click to toggle source

Adds specified username/password combination to current software instance

# File lib/softlayer/Software.rb, line 79
def add_user_password(username, password, options = {})
  raise ArgumentError, "The new password cannot be nil"   unless password
  raise ArgumentError, "The new username cannot be nil"   unless username
  raise ArgumentError, "The new password cannot be empty" if password.empty?
  raise ArgumentError, "The new username cannot be empty" if username.empty?

  raise Exception, "Cannot add username password, a Software Password already exists for the provided username" if self.has_user_password?(username.to_s)

  add_user_pw_template = {
    'softwareId' => self['id'].to_i,
    'password'   => password.to_s,
    'username'   => username.to_s
  }

  add_user_pw_template['notes'] = options['notes'].to_s if options.has_key?('notes')
  add_user_pw_template['port']  = options['port'].to_i  if options.has_key?('port')

  softlayer_client[:Software_Component_Password].createObject(add_user_pw_template)

  @passwords = nil
end
delete_user_password!(username) click to toggle source

Deletes specified username password from current software instance

This is a final action and cannot be undone. the transaction will proceed immediately.

Call it with extreme care!

# File lib/softlayer/Software.rb, line 109
def delete_user_password!(username)
  user_password = self.passwords.select { |sw_pw| sw_pw.username == username.to_s }

  unless user_password.empty?
    softlayer_client[:Software_Component_Password].object_with_id(user_password.first['id']).deleteObject
    @passwords = nil
  end
end
description(force_update=false) click to toggle source

Retrieve the manufacturer, name and version of a piece of software.

# File lib/softlayer/Software.rb, line 32
sl_dynamic_attr :description do |resource|
  resource.should_update? do
    #only retrieved once per instance
    @description == nil
  end

  resource.to_update do
    description = self.service.getSoftwareDescription
    description['longDescription']
  end
end
has_user_password?(username) click to toggle source

Returns whether or not one of the Software Password instances pertains to the specified user

# File lib/softlayer/Software.rb, line 121
def has_user_password?(username)
  self.passwords.map { |sw_pw| sw_pw.username }.include?(username)
end
name(force_update=false) click to toggle source

Retrieve the name of this specific piece of software.

# File lib/softlayer/Software.rb, line 48
sl_dynamic_attr :name do |resource|
  resource.should_update? do
    #only retrieved once per instance
    @name == nil
  end

  resource.to_update do
    description = self.service.getSoftwareDescription
    description['name']
  end
end
passwords(force_update=false) click to toggle source

Retrieve the Username/Password pairs used for access to this Software Installation.

# File lib/softlayer/Software.rb, line 64
sl_dynamic_attr :passwords do |resource|
  resource.should_update? do
    #only retrieved once per instance
    @passwords == nil
  end

  resource.to_update do
    passwords = self.service.getPasswords
    passwords.collect { |password_data| SoftwarePassword.new(softlayer_client, password_data) }
  end
end
service() click to toggle source

Returns the service for interacting with this software component through the network API

# File lib/softlayer/Software.rb, line 321
def service
  softlayer_client[:Software_Component].object_with_id(self.id)
end
softlayer_properties(object_mask = nil) click to toggle source

Make an API request to SoftLayer and return the latest properties hash for this object.

# File lib/softlayer/Software.rb, line 329
def softlayer_properties(object_mask = nil)
  my_service = self.service

  if(object_mask)
    my_service = my_service.object_mask(object_mask)
  else
    my_service = my_service.object_mask(self.class.default_object_mask)
  end

  my_service.getObject()
end