Class: SoftLayer::Software

Inherits:
ModelBase show all
Includes:
DynamicAttribute
Defined in:
lib/softlayer/Software.rb

Overview

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.

Instance Attribute Summary

Attributes inherited from ModelBase

#softlayer_client

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DynamicAttribute

included

Methods inherited from ModelBase

#[], #has_sl_property?, #initialize, #refresh_details, sl_attr, #to_ary

Constructor Details

This class inherits a constructor from SoftLayer::ModelBase

Class Method Details

.find_software_on_hardware(options_hash = {}) ⇒ Object

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



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# 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

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

  case options_hash[:hardware_type]
  when :bare_metal_instance
    hardware_data = .getBareMetalInstances
  when :hardware, nil
    hardware_data = .getHardware
  when :network_hardware
    hardware_data = .getNetworkHardware
  when :router
    hardware_data = .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 = {}) ⇒ Object

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



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# 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

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

  virtual_server_data = .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

Instance Method Details

#add_user_password(username, password, options = {}) ⇒ Object

Adds specified username/password combination to current software instance

Raises:

  • (ArgumentError) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# 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) ⇒ Object

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!



109
110
111
112
113
114
115
116
 
# 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 ⇒ Object

Retrieve the manufacturer, name and version of a piece of software. :call-seq:

description(force_update=false)



32
33
34
35
36
37
38
39
40
41
42
 
# 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) ⇒ Boolean

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

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/softlayer/Software.rb', line 121

def has_user_password?(username)
  self.passwords.map { |sw_pw| sw_pw.username }.include?(username)
end

#manufacturer_activation_code ⇒ Object

:attr_reader: manufacturer_activation_code The manufacturer code that is needed to activate a license.



21
 
# File 'lib/softlayer/Software.rb', line 21

sl_attr :manufacturer_activation_code, 'manufacturerActivationCode'

#manufacturer_license_key ⇒ Object

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



26
 
# File 'lib/softlayer/Software.rb', line 26

sl_attr :manufacturer_license_key,     'manufacturerLicenseInstance'

#name ⇒ Object

Retrieve the name of this specific piece of software. :call-seq:

name(force_update=false)



48
49
50
51
52
53
54
55
56
57
58
 
# 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 ⇒ Object

Retrieve the Username/Password pairs used for access to this Software Installation. :call-seq:

passwords(force_update=false)



64
65
66
67
68
69
70
71
72
73
74
 
# 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 ⇒ Object

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



321
322
323
 
# File 'lib/softlayer/Software.rb', line 321

def service
  softlayer_client[:Software_Component].object_with_id(self.id)
end

#softlayer_properties(object_mask = nil) ⇒ Object

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



329
330
331
332
333
334
335
336
337
338
339
 
# 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